What the gap is

The repo enforces a frozen-wire-schema invariant — "A change to types/schemas.ts must never alter what a codec emits or accepts on the wire" (the comment above the rule in packages/core-internal/eslint.config.mjs:34-37) — in two places, and both are keyed to the schemas' old home only:

1. eslint (packages/core-internal/eslint.config.mjs:38-55): for src/wire/rev*/**/*.ts, @typescript-eslint/no-restricted-imports restricts only the group ['**/types/schemas', '**/types/schemas.js'].
2. layeringInvariants (packages/core-internal/test/wire/layeringInvariants.test.ts:50): RUNTIME_SCHEMAS_IMPORT = /^(import|export)\s+(?!type\b)[^;]*?\bfrom\s+['\"][^'\"]*types\/schemas(?:\.js)?['\"]/m, applied to every file under src/wire/rev*/ by invariant (b) — a test that exists explicitly so "the lint rules cannot be silently weakened".

Neither pattern matches @modelcontextprotocol/core/internal or @modelcontextprotocol/core — both require the literal substring types/schemas in the module specifier.

Why this PR opens the bypass

Before the move, the dependency direction was core→core-internal, so no @modelcontextprotocol/core specifier could even resolve from inside core-internal. This PR reverses that: @modelcontextprotocol/core becomes a runtime dependency of core-internal (packages/core-internal/package.json), and packages/core-internal/tsconfig.json gains a package-wide paths alias for @modelcontextprotocol/core/internal → core/src/internal.ts. core/src/internal.ts does export * from './schemas', so the new specifier is a second canonical path to the exact same mutable schema objects the wire-isolation guards exist to freeze against.

Step-by-step proof

1. A contributor adding 2026-era wire support writes, inside src/wire/rev2026-07-28/:

   import { ContentBlockSchema } from '@modelcontextprotocol/core/internal';

   instead of freezing a copy into the rev directory.
2. typecheck: passes — the tsconfig paths alias resolves the specifier to core/src/internal.ts.
3. lint: passes — '@modelcontextprotocol/core/internal' matches neither '**/types/schemas' nor '**/types/schemas.js'.
4. layeringInvariants (b): passes — the specifier contains no types/schemas substring, so RUNTIME_SCHEMAS_IMPORT doesn't match.
5. runtime: works — core is a real dependency, and the bundles keep core/internal external.
6. Later, a spec-tracking widening of ContentBlockSchema in core/src/schemas.ts retroactively changes what the supposedly-frozen 2026 era accepts on the wire — with every gate green. That is precisely the drift the invariant was written to prevent.

Why nothing else catches it

The PR's own new guards cover other directions but not this one: schemaShims.test.ts only pins the three re-export shims to be forwarding-only, and coreBoundary.test.ts only checks that names the client dist imports exist in core's built exports. A wire/rev file importing a perfectly valid mutable schema trips neither. Notably, the PR did update its other guard keyed to the schemas' location — wireOnlyHiding.test.ts now reads core/src/schemas.ts directly — so leaving the two wire-isolation guards on the retired path looks like an oversight rather than a design choice.

Impact and fix

I verified (grep) that no file under src/wire/ imports any @modelcontextprotocol/core specifier today, so nothing breaks on merge — this is future-drift insurance with a hole in it, not a live defect; hence nit rather than blocking. The fix is two one-line pattern extensions: add '@modelcontextprotocol/core' and '@modelcontextprotocol/core/internal' (plus subpath-glob variants as appropriate) to the eslint group in eslint.config.mjs, and extend RUNTIME_SCHEMAS_IMPORT in layeringInvariants.test.ts to also match the core specifiers, keeping the existing allowTypeImports/type-only exemptions.

Issue 1: incomplete sentinel set can permanently wedge the dist

The helper's own docstring states the invariant: "Every caller waits on the same complete set: if callers checked their own subsets, a partial dist (from an interrupted build) could satisfy one caller's fast path…" — but the registered set itself is a subset of what the callers read. DIST_SENTINELS.client lists only index.mjs and stdio.mjs, while barrelClean.test.ts reads dist/index.d.mts and dist/index.d.cts (via rootExportBlockOf), dist/shimsNode.mjs / shimsWorkerd.mjs / shimsBrowser.mjs, and requires dist/validators/ajv.cjs; coreBoundary.test.ts reads every top-level *.mjs chunk.

Step-by-step failure: (1) On a cold checkout, worker A takes the lock and runs pnpm build. tsdown emits the rolldown JS bundles (including both sentinels) quickly; the resolver: 'tsc' dts pass is a distinctly slower, later phase. (2) The build is killed mid-flight — by the helper's own BUILD_TIMEOUT_MS = 60_000 execFile timeout, or a Ctrl-C propagating SIGINT to the child. The finally block still removes the lock. (3) dist now contains index.mjs + stdio.mjs but no declaration files. (4) On every subsequent run, haveAll() is true and no lock exists, so the fast path returns immediately — and even a worker that somehow takes the lock skips the build because !haveAll() is false. Per the design comment, "once the dist exists nobody ever rebuilds." (5) Every later test run fails with an ENOENT on index.d.mts (or a regex mismatch) — a confusing failure that points nowhere near the actual cause — and the state never self-heals until someone manually deletes dist/ or runs pnpm build.

Fix: include one artifact from each build phase in the sentinel list (e.g. add index.d.mts for the dts phase and shimsBrowser.mjs for the entry set), or have the build path write a completion-marker file as its last step and use that as the sole sentinel.

Issue 2: the stale-lock steal is not atomic

The steal path is stat → decide → rmSync(recursive, force) → continue → mkdirSync. The decision is made from a stat of the old stale lock, but rmSync unconditionally deletes whatever directory exists at lockDir at rm-time, with no re-check.

Step-by-step interleaving: a leftover .dist-build-lock from a previously killed run (SIGKILL/OOM — the documented scenario the steal exists for) means every vitest worker of the next run hits the steal path simultaneously at startup, since barrelClean.test.ts and coreBoundary.test.ts both call ensureBuilt(clientPkgDir) from separate parallel workers and all observe age > STALE_LOCK_MS at once. Then: (1) C stats the stale lock and decides to steal; (2) B stats it too, rmSyncs the old lock, continues, mkdirSyncs a fresh lock, and spawns pnpm build; (3) C — delayed between its stat and its rm — now executes rmSync(force: true), silently deleting B's fresh lock; (4) C's mkdirSync succeeds and C also spawns pnpm build. Two concurrent builds now run in the same package, and tsdown's clean: true wipes dist out from under the sibling build; worse, with B's lock gone, any third worker's fast path (haveAll() && !existsSync(lockDir)) can return and start reading a dist that C's clean step is about to delete. This is precisely the failure mode the file header says the helper prevents, reintroduced in its own recovery path.

Fix: make the steal atomic — e.g. renameSync the stale lock dir to a unique name (rename is atomic; only one stealer succeeds, losers get ENOENT and re-loop as ordinary waiters), or re-stat/verify the lock's mtime immediately after acquiring.

Why nit, not blocking

Both issues live in test-only infrastructure and fail loudly (ENOENT / a flaky red run), never as a silent false green, and nothing shipped to consumers is affected. Issue 1 requires an interrupted build on a local machine (CI runs from clean checkouts or pre-built dists) and recovers with one pnpm build; issue 2 additionally requires a dead-worker stale lock plus a microseconds-wide interleaving, and usually self-heals on the next run. But since this file's entire reason to exist is making on-demand builds race-free, both fixes are cheap and worth taking: they're each roughly a one-line change to freshly-written locking code.

What's stale. This PR makes @modelcontextprotocol/core an exact-pinned runtime dependency of client, server, and server-legacy (each package.json now declares "@modelcontextprotocol/core": "workspace:*"), and the built bundles resolve @modelcontextprotocol/core/internal as a live external import — pinned by the new coreBoundary.test.ts. The earlier review round flagged two docs asserting the old topology, and commit 68688c9 fixed both (docs/get-started/packages.md:69 and docs/advanced/wire-schemas.md:60 now say core "arrives transitively" as the shared runtime schema graph). But a third instance survived: docs/migration/upgrade-to-v2.md:1326-1329 still reads "It is runtime-neutral (its only dependency is zod) and is not required by client / server — install it only if you import the raw schemas directly."\n\nStep-by-step proof that the sentence is false post-merge. (1) A v1 user upgrading per this guide runs npm install @modelcontextprotocol/client (or server). (2) npm reads the client's dependencies, resolves @modelcontextprotocol/core transitively, and it lands in node_modules on every install — directly contradicting "not required by client / server". (3) At runtime the installed client's dist chunks contain live import { … } from '@modelcontextprotocol/core/internal' statements, so the dependency is real at module-resolution level, not just in the manifest. A grep over docs/ and package READMEs confirms this is the only surviving occurrence of the old "not required / never depend / never install" framing after 68688c9.\n\nWhy it matters beyond mere staleness. The "install it only if…" framing in the v1→v2 migration guide — the doc most upgrading users actually read — invites users to pin their own core version alongside client/server. Because core/client/server/server-legacy now release as a changesets fixed group with exact pins, a version-skewed self-pinned core resolved in place of the paired one fails at import time with ERR_PACKAGE_PATH_NOT_EXPORTED (the PR description names this failure mode). So the sentence steers readers toward exactly the configuration the fixed group and exact pins were added to prevent.\n\nWhy nothing in the PR catches it. The drift guards added here (coreBoundary.test.ts, schemaShims.test.ts, packageTopologyPins.test.ts) pin build artifacts and manifests, not prose. The doc-topology fix in 68688c9 was scoped to the two files the earlier comment named, and the migration guide was not in the diff.\n\nFix. A one-sentence reword at upgrade-to-v2.md:1328 matching the corrected language in packages.md/wire-schemas.md — e.g.: "It is runtime-neutral (its only dependency is zod). client / server resolve their shared schema graph from it at runtime, so it already arrives transitively in your tree; add it to your own dependencies only when you import the raw schemas directly." The runtime-neutral / zod-only half of the claim remains true and should stay.\n\nSeverity. Nit: doc-only — nothing breaks at runtime if merged as-is, and the "only import it directly if you need raw schemas" advice half remains sound. But it is the same class of stale prose the author already accepted and fixed twice in this PR, so finishing the sweep is cheap and worthwhile.